Skip to main content

Banner

warning

This is the documentation for the Advanced API. Most developers should use our Simplified API (documented in Banner), which comes with several built-in features such as:

  • Automatic ad loading
  • Retries for failed requests
  • Simplified lifecycle management

Only use the Advanced API if you need fine-grained control over the ad loading and presentation lifecycle.

Note: The Advanced API is only available in Swift. For Objective-C, please use the Simplified API.

The Advanced API provides direct access to individual Banner instances, giving you complete control over when and how ads are loaded and displayed.

Create a Banner instance​

// Inside a view controller's viewDidLoad
let banner = Banner.create(placementId: "<placement-id>",
                           size: UI_USER_INTERFACE_IDIOM() == .phone ? .phone : .tablet,
                           viewController: self)

Register ad callbacks​

// Assign a delegate to handle the ad callbacks
banner.delegate = self

// [...]

// Load Callbacks
func didCompletePrebidding(result: PrebiddingResults) {
    print("Banner client-side bidding finished!")
}

func didLoad(result: LoadResult) {
    print("Banner loaded!")
}

func failedToLoad(result: LoadResult?, error: LoadError) {
    print("Banner failed to load. Reason: \(error.localizedDescription)")
}

// Impression Callback
func didRecordImpression(data: ImpressionData) {
    print("Banner impression, with revenue: \(data.revenue)")
}

Load an ad​

banner.load()

Load an ad (with custom properties)​

var properties = CustomProperties()
properties.addString(key: "game_mode", value: "classic")
banner.load(customProperties: properties)

Displaying the banner​

The most common practice is to add the banner view to the view hierarchy either:

  • After creating the Banner instance.
  • After the didLoad(result:) delegate callback is called.
// Optionally, set the ad space where the banner will be shown
banner.adSpace = "banner-ad-space"

let bannerView = banner.view
view.addSubview(bannerView)

bannerView.translatesAutoresizingMaskIntoConstraints = false
bannerView.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor).isActive = true
bannerView.centerXAnchor.constraint(equalTo: view.centerXAnchor).isActive = true

After being displayed for some time, our banner fires a load() call automatically to refresh its contents. You can configure this time through our Admin tool for each one of your banners.

Our banner has a built-in auto retry for failed load attempts. This means that when a banner fails to load, it will retry again until it loads successfully. Time between each retry attempt will increase using an exponential backoff. You should not add any retry logic on your end, as it may interfere with our retry behaviour.

Complete example​

BannerAdvancedViewController.swift
import UIKit
import XMediator

class BannerAdvancedViewController: UIViewController {
    private var banner: Banner?

    override func viewDidLoad() {
        super.viewDidLoad()

        let banner = Banner.create(placementId: "<placement-id>",
                                   size: UI_USER_INTERFACE_IDIOM() == .phone ? .phone : .tablet,
                                   viewController: self)
        banner.delegate = self
        self.banner = banner

        addBannerToViewHierarchy(banner.view)
    }

    private func addBannerToViewHierarchy(_ bannerView: UIView) {
        view.addSubview(bannerView)

        bannerView.translatesAutoresizingMaskIntoConstraints = false
        bannerView.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor).isActive = true
        bannerView.centerXAnchor.constraint(equalTo: view.centerXAnchor).isActive = true
    }

    @IBAction func loadTouchUp(_ sender: Any) {
        banner?.load()
    }
}

extension BannerAdvancedViewController: BannerDelegate {
    func didCompletePrebidding(result: PrebiddingResults) {
        print("Banner client-side bidding finished!")
    }

    func didLoad(result: LoadResult) {
        print("Banner loaded!")
    }

    func failedToLoad(result: LoadResult?, error: LoadError) {
        print("Banner failed to load. Reason: \(error.localizedDescription)")
    }

    func didRecordImpression(data: ImpressionData) {
        print("Banner impression, with revenue: \(data.revenue)")
    }

    func didClick() {
        print("Banner was clicked!")
    }
}